Add Anti-Censorship features support and udp over tcp obfuscator on Linux and Android by encrypt94 · Pull Request #11275 · mozilla-mobile/mozilla-vpn-client

encrypt94 · 2026-05-13T12:49:30Z

Description

This PR adds support for anti-censorship features / obfuscators.
A new menu similar to "Privacy Features" , allows users to configure the following anti-censorship features when available on the platform (the menu item will be hidden if a feature is not available.)

Connect using port 53 - not an obfuscation method, simply exposes an existing feature and allows the user to always use port 53 (compatible with LWO)
Udp over Tcp - the only obfuscator implemented in this pr, uses udp over tcp crate to tunnel WireGuard traffic over TCP
Lighweight obfuscation - lighweight WireGuard scrambler, planned as the next obfuscator
MASQUE - tunnel WireGuard traffic over CONNECT-UDP
Shadowsocks - tunnel WireGuard traffic over shadowsocks
obfuscators description strings and anti-censorship help text can be improved, help is super appreciated :)

Obfuscators are implemented in a Rust crate located under the obfuscators/ directory.
An obfuscator acts as a local UDP proxy running on a local UDP port, the outbound sockets must be protected to avoid traffic loops.

On Linux (and Windows in the future except for the marking part):

The crate produces a standalone binary (mozilla-obfuscator) installed alongside the daemon.
When the VPN is turned on or a server switch occurs, the obfuscator is launched.
The obfuscator requires CAP_NET_ADMIN privileges to set SO_MARK.
The obfuscator listens on a free port and writes the port to stdout.
The MozillaVPN daemon parses the port from stdout and rewrites the server/port in WireGuard's peer config (alternatively, we can probe a free port in the daemon and send it to the obfuscator but this approach may be prone to race contitions)

On Android (and likely iOS in a similar way):

The crate is accessed via FFI using JNA.
VPNActivity starts the obfuscator.
VPNActivity calls protect on the obfuscator's sockets.
VPNActivity rewrites the local port in the configuration.

This architecture was chosen because most of the libraries required to implement obfuscation protocols are available in the Rust ecosystem: UDP-over-TCP, Shadowsocks, and QUIC stacks.

Impacts on the rust build bits:

added add_rust_binary in rustlang.cmake and refactored add_rust_library to split out shared parts
updated rust to 1.91 because:
- udp-over-tcp requires rust >= 1.87
- only rust 1.89 and 1.91 are available in Ubuntu repost
- i hit a weird bug with cargo 1.8x installed from ubuntu repos being unable to install crates from git (solved in 1.91)
rust 1.91 is not available in debian:bookworm so is now installed using rustup in linux-qt6-build

UI

When Anti-Censorship features are enabled, a “Anti-Censorship is on” label appears below the timer.

A new Anti-Censorship Features menu is available in Settings.

When Anti-Censorship features are available on the platform, a toggle switch will be displayed in the menu with name and brief description.
Enabling one feature will automatically disable any previously enabled feature, except for the “Use Port 53” feature, which is compatible with LWO.

Help text

Reference

VPN-7588 - Create generic obfuscation interface for anti censorship features
VPN-7566 - Create anti censorship features menu
VPN-7582 - Implement UDP over TCP on Linux
VPN-7583 - Implement UDP over TCP on Android

Checklist

My code follows the style guidelines for this project
I have not added any packages that contain high risk or unknown licenses (GPL, LGPL, MPL, etc. consult with DevOps if in question)
I have performed a self review of my own code
I have commented my code PARTICULARLY in hard to understand areas
I have added thorough tests where needed

oskirby · 2026-05-13T23:05:35Z

I've had kind of a love/hate relationship with building rust binaries over the years, but this might be a good case for splitting the obfuscator into a standalone binary that can be invoked by the daemon as needed rather than baking it into the client.

The obfuscator should only ever operate on unprivileged information, should require no root permissions, and it probably has a pretty heavy workload given that it needs to live in the packet processing loop.

QProcess * obfuscator = new QProcess(this);
QStringList args;
args << "--method" << "lwo";
args << "--pubkey" << config.m_serverPublicKey;
args << "--server" << config.m_serverIpv4AddrIn;
obfuscator->start("/usr/bin/mozillavpn-obfuscator", args);

connect(obfuscator, &QProcess::started, this, &Example::handleObfuscatorStarted);
connect(obfuscator, &QProcess::finished, this, &Example::handleObfuscatorFinished);

…ndgen, with an the udp2tcp implementation. Wire the obfuscator into the controller and daemon so the daemon can spin up a local obfuscation tunnel and the WireGuard peer is pointed at the obfuscator'slocal UDP port.

…update daemon.cpp, drop ffi calls and use QProcess to call the obfuscator

… library build helpers into smaller reusable functions shared with the binaries helpers

…fuscator ffi interface and instantiate the obfuscator and protect the sockets

…roxy_options; class=Invalid (3)' bug when installing crates from git

…untu only provides 1.85 and 1.89 in its repos.

…equires 1.88

…was generating a cyle (only when called by dpkg-buildpackage) use a custom target that sets sets ${TARGET_NAME}_EXECUTABLE

…op obfuscator for wasm and ios, on desktop platform use qprocessobfusctator on wasm use the dummy one

flodolo · 2026-06-03T05:09:54Z


 settings:
  privacySettings: Privacy features
+  antiCensorshipSettings: Anti-Censorship features


Is this coming from the Content Team? Is this terminology approved by Legal?

Similar question - I'm curious if you'd be open to working on wordsmithing a bunch of these. "What can xxxx do for me?", for instance, feels like a different voice than most of our product copy.

Is this coming from the Content Team? Is this terminology approved by Legal?
Thanks for raising this. It’s not coming from the Content Team and hasn’t been approved by Legal yet. Legal is currently reviewing the language.

Similar question - I'm curious if you'd be open to working on wordsmithing a bunch of these. "What can xxxx do for me?", for instance, feels like a different voice than most of our product copy.

Sure i'm totally open to change the descriptions! i'll try to come up with something that feels more aligned with the rest of our product copy :) suggestions are super appreciated!

flodolo · 2026-06-03T05:10:24Z

+  antiCensorshipSettingsWarning: These options may cause connection stability issues.
+  antiCensorshipPort53Title: Connect using port 53
+  antiCensorshipPort53Body: This may help on networks that block ports or UDP traffic.
+  antiCensorshipMasqueTitle: MASQUE


Why is this uppercase? Should it be translated? Same question for SHADOWSOCKS later.

Shadowsocks casing is an error. MASQUE is an acronym, so it should be kept uppercase. Both of them are proper nouns and should not be translated

mcleinman · 2026-06-03T17:03:00Z

+            onClicked: {
+                if(MZSettings.obfuscationMethod == modelData.settingValue) {
+                    MZSettings.obfuscationMethod = MZSettings.NoObfuscation;
+                } else {
+                    MZSettings.obfuscationMethod = modelData.settingValue;
+                    // Maybe automatically disable alwaysPort53 when enabling an obfuscation method 


If these options are mutually exclusive, we should not use switches here - we should use radio buttons, like in the DNS settings screen.

Good point. Obfuscators are mutually exclusive, and "Always use port 53" only works with LWO. What do you think about using a toggle switch for "Always use port 53" and radio buttons for the obfuscators, and then disabling the switch when anything other than LWO is selected?

What about splitting it into two radio buttons? Something like "LWO via typical ports" and "LWO using port 53"? We don't need to touch the settings structure in code - under the hood, we just set those settings as appropriate.

mcleinman · 2026-06-03T18:28:17Z

This is amazing, thank you! I'm focusing on UI right now, will let others handle the underlying code who are better positioned to review that piece.

mcleinman · 2026-06-04T19:57:44Z


 settings:
  privacySettings: Privacy features
+  antiCensorshipSettings: Anti-Censorship features


I think this needs to be done in conjunction with legal, but I'm wondering if "anti-censorship features" is immediately understandable by the average person.

Maybe something like "Advanced networking features" or "restricted network settings" or "alternative connection methods" or "hostile network defense" or "censorship resistance" or "network workaround" or... maybe this is something we can talk out in a meeting next week?

And of course, if we rename this we'll need to update many of these strings.

mcleinman · 2026-06-04T19:59:30Z

 settings:
  privacySettings: Privacy features
+  antiCensorshipSettings: Anti-Censorship features
+  antiCensorshipSettingsWarning: These options may cause connection stability issues.


Suggested change

antiCensorshipSettingsWarning: These options may cause connection stability issues.

antiCensorshipSettingsWarning: These options should be used when a network operator is blocking connection to VPN servers. They may cause stability issues.

Should we also include something about how this will not help with a website blocking VPN connections? This seems important for setting user expectations.

mcleinman · 2026-06-04T20:00:23Z

+  antiCensorshipSettings: Anti-Censorship features
+  antiCensorshipSettingsWarning: These options may cause connection stability issues.
+  antiCensorshipPort53Title: Connect using port 53
+  antiCensorshipPort53Body: This may help on networks that block ports or UDP traffic.


Suggested change

antiCensorshipPort53Body: This may help on networks that block ports or UDP traffic.

antiCensorshipPort53Body: This may help on networks that block specific ports or UDP traffic.

mcleinman · 2026-06-04T20:01:02Z

+  antiCensorshipPort53Title: Connect using port 53
+  antiCensorshipPort53Body: This may help on networks that block ports or UDP traffic.
+  antiCensorshipMasqueTitle: MASQUE
+  antiCensorshipMasqueBody: This may help on networks that block VPN protocols by disguising VPN traffic as regular HTTPS traffic.


Suggested change

antiCensorshipMasqueBody: This may help on networks that block VPN protocols by disguising VPN traffic as regular HTTPS traffic.

antiCensorshipMasqueBody: This disguises VPN traffic as regular HTTPS traffic, and may help on networks that block VPN protocols by .

mcleinman · 2026-06-04T20:01:33Z

  privacySettings: Privacy features
+  antiCensorshipSettings: Anti-Censorship features
+  antiCensorshipSettingsWarning: These options may cause connection stability issues.
+  antiCensorshipPort53Title: Connect using port 53


Suggested change

antiCensorshipPort53Title: Connect using port 53

antiCensorshipPort53Title: Always connect using port 53

mcleinman · 2026-06-04T20:01:58Z

+  antiCensorshipShadowsocksTitle: SHADOWSOCKS
+  antiCensorshipShadowsocksBody: A reliable censorship circumvention protocol that may help bypass restrictive or heavily filtered networks.
+  antiCensorshipUdpOverTcpTitle: UDP over TCP
+  antiCensorshipUdpOverTcpBody: This may help on networks that block UDP traffic by tunneling it over TCP.


Suggested change

antiCensorshipUdpOverTcpBody: This may help on networks that block UDP traffic by tunneling it over TCP.

antiCensorshipUdpOverTcpBody: This tunnels UDP traffic over TCP, and may help on networks that block UDP traffic.

mcleinman · 2026-06-04T20:02:37Z

+  antiCensorshipMasqueTitle: MASQUE
+  antiCensorshipMasqueBody: This may help on networks that block VPN protocols by disguising VPN traffic as regular HTTPS traffic.
+  antiCensorshipLwoTitle: Lightweight obfuscation
+  antiCensorshipLwoBody: The fastest obfuscation method. May help on networks that detect or block WireGuard traffic without adding significant overhead.


Can we give a little bit more here? We give a minor technical explanation for the others, and this once we just call "lightweight" with no detail.

mcleinman · 2026-06-04T20:04:18Z

+  antiCensorshipLwoTitle: Lightweight obfuscation
+  antiCensorshipLwoBody: The fastest obfuscation method. May help on networks that detect or block WireGuard traffic without adding significant overhead.
+  antiCensorshipShadowsocksTitle: SHADOWSOCKS
+  antiCensorshipShadowsocksBody: A reliable censorship circumvention protocol that may help bypass restrictive or heavily filtered networks.


Suggested change

antiCensorshipShadowsocksBody: A reliable censorship circumvention protocol that may help bypass restrictive or heavily filtered networks.

antiCensorshipShadowsocksBody: [Insert a phrase of technical detail.] This may help bypass restrictive or heavily filtered networks, and sometimes works when all other ones do not.

Are there tradeoffs to this, like in speed? Is this the first one folks should try, or the last?

mcleinman · 2026-06-04T20:05:11Z

+    value: Anti-Censorship features can help when your provider or network blocks VPN or UDP traffic.
+    comment: Body label for the Anti-Censorship features help sheet
+  antiCensorshipBody2:
+    value: These features may slow down your connection, so turn them off when you no longer need them.


Suggested change

value: These features may slow down your connection, so turn them off when you no longer need them.

value: These features may slow down the connection, so turn them off when they are not needed.

mcleinman · 2026-06-04T20:05:48Z

+    value: Anti-Censorship features
+    comment: Title label for the Anti-Censorship features help sheet
+  antiCensorshipHeader:
+    value: What can Anti-Censorship features do for me?


Maybe remove this header? I'm not sure it adds anything, given that we have the title as well.

encrypt94 changed the title ~~Add obfuscators and udp over tcp obfuscator on Linux~~ DRAFT Add obfuscators and udp over tcp obfuscator on Linux May 13, 2026

encrypt94 changed the title ~~DRAFT Add obfuscators and udp over tcp obfuscator on Linux~~ DRAFT Add Anti-Censorship features support and udp over tcp obfuscator (Linux only) May 13, 2026

encrypt94 force-pushed the marco/add-obfuscators branch 3 times, most recently from cbd6d7e to ba41012 Compare May 13, 2026 22:48

encrypt94 force-pushed the marco/add-obfuscators branch from ba41012 to 6b6f676 Compare May 13, 2026 23:09

encrypt94 changed the title ~~DRAFT Add Anti-Censorship features support and udp over tcp obfuscator (Linux only)~~ DRAFT Add Anti-Censorship features support and udp over tcp obfuscator (Linux and Android only) Jun 1, 2026

encrypt94 changed the title ~~DRAFT Add Anti-Censorship features support and udp over tcp obfuscator (Linux and Android only)~~ DRAFT Add Anti-Censorship features support and udp over tcp obfuscator on Linux and Android Jun 1, 2026

encrypt94 force-pushed the marco/add-obfuscators branch 3 times, most recently from 4386cc2 to 7c124ff Compare June 1, 2026 13:06

encrypt94 added 11 commits June 1, 2026 16:55

Add features, settings and ui bits for Anti-Censorship features

dc6b1a5

update lockfile

62f190b

bump cargo to 1.89 in base image to user version 4 lockfile

785169b

update obfuscators crate to provide also a standalone executable and …

211a452

…update daemon.cpp, drop ffi calls and use QProcess to call the obfuscator

add helper to build rust binries in rustlang.cmake, refactor the rust…

42da0fa

… library build helpers into smaller reusable functions shared with the binaries helpers

add obfuscators support for android using JNA, VPNService call the ob…

0e52aaf

…fuscator ffi interface and instantiate the obfuscator and protect the sockets

update cargo lockfile

2fe705c

install cargo 1.91 instead of 1.8* due to 'invalid version 0 on git_p…

bdbeea2

…roxy_options; class=Invalid (3)' bug when installing crates from git

bump minimum rust version to 1.89. udp over tcp requires 1.87, but ub…

a26d560

…untu only provides 1.85 and 1.89 in its repos.

bump minimum rust version to 1.89. udp over tcp requires 1.87, time r…

9d37f45

…equires 1.88

encrypt94 force-pushed the marco/add-obfuscators branch 2 times, most recently from 4f85b01 to 5eb093d Compare June 1, 2026 15:07

correctly link /usr/bin/cargo and /usr/bin/rustc

dbfe054

encrypt94 force-pushed the marco/add-obfuscators branch from 5eb093d to dbfe054 Compare June 1, 2026 15:17

encrypt94 added 3 commits June 1, 2026 17:24

keep linter happy

34ec956

rustc is a symlink

d3d8898

step back from add_rust_binary creating an IMPORTED executable as it …

4dcdada

…was generating a cyle (only when called by dpkg-buildpackage) use a custom target that sets sets ${TARGET_NAME}_EXECUTABLE

encrypt94 force-pushed the marco/add-obfuscators branch 3 times, most recently from 2ce192f to 5005e81 Compare June 2, 2026 14:31

replace the single-file obfuscator with an abstract one and add a no-…

ef8ab9b

…op obfuscator for wasm and ios, on desktop platform use qprocessobfusctator on wasm use the dummy one

encrypt94 force-pushed the marco/add-obfuscators branch from 5005e81 to ef8ab9b Compare June 2, 2026 15:04

cleanup, remove cbindgen stuff, we don't use cffi anymore

30fca1b

encrypt94 requested review from artfwo, mcleinman, oskirby and strseb June 2, 2026 19:19

encrypt94 changed the title ~~DRAFT Add Anti-Censorship features support and udp over tcp obfuscator on Linux and Android~~ Add Anti-Censorship features support and udp over tcp obfuscator on Linux and Android Jun 2, 2026

encrypt94 marked this pull request as ready for review June 2, 2026 19:30

encrypt94 requested review from a team and flodolo as code owners June 2, 2026 19:30

encrypt94 requested review from abhishekmadan30 and removed request for a team June 2, 2026 19:30

flodolo requested changes Jun 3, 2026

View reviewed changes

mcleinman reviewed Jun 3, 2026

View reviewed changes

oskirby mentioned this pull request Jun 3, 2026

Update cargo in base taskcluster dockerfile to 1.85 #11334

Merged

5 tasks

mcleinman reviewed Jun 4, 2026

View reviewed changes

	antiCensorshipSettingsWarning: These options may cause connection stability issues.
	antiCensorshipSettingsWarning: These options should be used when a network operator is blocking connection to VPN servers. They may cause stability issues.

	antiCensorshipPort53Body: This may help on networks that block ports or UDP traffic.
	antiCensorshipPort53Body: This may help on networks that block specific ports or UDP traffic.

	antiCensorshipMasqueBody: This may help on networks that block VPN protocols by disguising VPN traffic as regular HTTPS traffic.
	antiCensorshipMasqueBody: This disguises VPN traffic as regular HTTPS traffic, and may help on networks that block VPN protocols by .

	antiCensorshipPort53Title: Connect using port 53
	antiCensorshipPort53Title: Always connect using port 53

	antiCensorshipUdpOverTcpBody: This may help on networks that block UDP traffic by tunneling it over TCP.
	antiCensorshipUdpOverTcpBody: This tunnels UDP traffic over TCP, and may help on networks that block UDP traffic.

	antiCensorshipShadowsocksBody: A reliable censorship circumvention protocol that may help bypass restrictive or heavily filtered networks.
	antiCensorshipShadowsocksBody: [Insert a phrase of technical detail.] This may help bypass restrictive or heavily filtered networks, and sometimes works when all other ones do not.

	value: These features may slow down your connection, so turn them off when you no longer need them.
	value: These features may slow down the connection, so turn them off when they are not needed.

Conversation

encrypt94 commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

UI

Reference

Checklist

Uh oh!

oskirby commented May 13, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcleinman Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcleinman commented Jun 3, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

encrypt94 commented May 13, 2026 •

edited

Loading

mcleinman Jun 4, 2026 •

edited

Loading